// Copyright (C) 2024 EA group inc.
// Author: Jeff.li lijippy@163.com
// All rights reserved.
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published
// by the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
//
// -----------------------------------------------------------------------------
// File: symbolize.h
// -----------------------------------------------------------------------------
//
// This file configures the Turbo symbolizer for use in converting instruction
// pointer addresses (program counters) into human-readable names (function
// calls, etc.) within Turbo code.
//
// The symbolizer may be invoked from several sources:
//
//   * Implicitly, through the installation of an Turbo failure signal handler.
//     (See failure_signal_handler.h for more information.)
//   * By calling `Symbolize()` directly on a program counter you obtain through
//     `turbo::GetStackTrace()` or `turbo::GetStackFrames()`. (See stacktrace.h
//     for more information.
//   * By calling `Symbolize()` directly on a program counter you obtain through
//     other means (which would be platform-dependent).
//
// In all of the above cases, the symbolizer must first be initialized before
// any program counter values can be symbolized. If you are installing a failure
// signal handler, initialize the symbolizer before you do so.
//
// Example:
//
//   int main(int argc, char** argv) {
//     // Initialize the Symbolizer before installing the failure signal handler
//     turbo::InitializeSymbolizer(argv[0]);
//
//     // Now you may install the failure signal handler
//     turbo::FailureSignalHandlerOptions options;
//     turbo::InstallFailureSignalHandler(options);
//
//     // Start running your main program
//     ...
//     return 0;
//  }
//
#ifndef TURBO_DEBUGGING_SYMBOLIZE_H_
#define TURBO_DEBUGGING_SYMBOLIZE_H_

#include <turbo/debugging/internal/symbolize.h>

namespace turbo {

    // InitializeSymbolizer()
    //
    // Initializes the program counter symbolizer, given the path of the program
    // (typically obtained through `main()`s `argv[0]`). The Turbo symbolizer
    // allows you to read program counters (instruction pointer values) using their
    // human-readable names within output such as stack traces.
    //
    // Example:
    //
    // int main(int argc, char *argv[]) {
    //   turbo::InitializeSymbolizer(argv[0]);
    //   // Now you can use the symbolizer
    // }
    void InitializeSymbolizer(const char *argv0);

    //
    // Symbolize()
    //
    // Symbolizes a program counter (instruction pointer value) `pc` and, on
    // success, writes the name to `out`. The symbol name is demangled, if possible.
    // Note that the symbolized name may be truncated and will be NUL-terminated.
    // Demangling is supported for symbols generated by GCC 3.x or newer). Returns
    // `false` on failure.
    //
    // Example:
    //
    //   // Print a program counter and its symbol name.
    //   static void DumpPCAndSymbol(void *pc) {
    //     char tmp[1024];
    //     const char *symbol = "(unknown)";
    //     if (turbo::Symbolize(pc, tmp, sizeof(tmp))) {
    //       symbol = tmp;
    //     }
    //     turbo::PrintF("%p  %s\n", pc, symbol);
    //  }
    bool Symbolize(const void *pc, char *out, int out_size);

}  // namespace turbo

#endif  // TURBO_DEBUGGING_SYMBOLIZE_H_
